home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / catD / copyin.z / copyin
Encoding:
Text File  |  1998-10-30  |  8.3 KB  |  131 lines
  1.  
  2.  
  3.  
  4. ccccooooppppyyyyiiiinnnn((((DDDD3333))))                                                          ccccooooppppyyyyiiiinnnn((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _cccc_oooo_pppp_yyyy_iiii_nnnn - copy data from a user buffer to a driver buffer
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  14.      _iiii_nnnn_tttt _cccc_oooo_pppp_yyyy_iiii_nnnn_((((_cccc_aaaa_dddd_dddd_rrrr______tttt _u_s_e_r_b_u_f_,,,, _cccc_aaaa_dddd_dddd_rrrr______tttt _d_r_i_v_e_r_b_u_f_,,,, _ssss_iiii_zzzz_eeee______tttt _c_o_u_n_t_))))_;;;;
  15.  
  16.    AAAArrrrgggguuuummmmeeeennnnttttssss
  17.      _u_s_e_r_b_u_f   User source address from which copy is made.
  18.  
  19.      _d_r_i_v_e_r_b_u_f Driver destination address to which copy is made.
  20.  
  21.      _c_o_u_n_t     Number of bytes to copy.
  22.  
  23. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  24.      _cccc_oooo_pppp_yyyy_iiii_nnnn copies _c_o_u_n_t bytes of data from the user virtual address specified
  25.      by _u_s_e_r_b_u_f to the kernel virtual address specified by _d_r_i_v_e_r_b_u_f.
  26.  
  27.    RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
  28.      If the copy is successful, 0 is returned.  Otherwise, -1 is returned to
  29.      indicate that the specified user address range is not valid.
  30.  
  31. UUUUSSSSAAAAGGGGEEEE
  32.      The driver must ensure that adequate space is allocated for the
  33.      destination address.
  34.  
  35.      _cccc_oooo_pppp_yyyy_iiii_nnnn chooses the best algorithm based on address alignment and number
  36.      of bytes to copy.  Although the source and destination addresses are not
  37.      required to be word aligned, word aligned addresses may result in a more
  38.      efficient copy.
  39.  
  40.      Drivers usually convert a return value of -1 into an _EEEE_FFFF_AAAA_UUUU_LLLL_TTTT error.
  41.  
  42.    LLLLeeeevvvveeeellll
  43.      Base only.
  44.  
  45.    SSSSyyyynnnncccchhhhrrrroooonnnniiiizzzzaaaattttiiiioooonnnn CCCCoooonnnnssssttttrrrraaaaiiiinnnnttttssss
  46.      Can sleep.
  47.  
  48.      Driver-defined basic locks and read/write locks may not be held across
  49.      calls to this function.
  50.  
  51.      Driver-defined sleep locks may be held across calls to this function.
  52.  
  53.    WWWWaaaarrrrnnnniiiinnnnggggssss
  54.      The driver source buffer must be completely within the kernel address
  55.      space, or the system can panic.
  56.  
  57.  
  58.  
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. ccccooooppppyyyyiiiinnnn((((DDDD3333))))                                                          ccccooooppppyyyyiiiinnnn((((DDDD3333))))
  70.  
  71.  
  72.  
  73.      When holding sleep locks across calls to this function, multithreaded
  74.      drivers must be careful to avoid creating a deadlock.  During the data
  75.      transfer, page fault resolution might result in another I/O to the same
  76.      device.  For example, this could occur if the driver controls the disk
  77.      drive used as the swap device.
  78.  
  79.    EEEExxxxaaaammmmpppplllleeeessss
  80.      A driver _iiii_oooo_cccc_tttt_llll(D2) routine (line 5) can be used to get or set device
  81.      attributes or registers.  If the specified command is _XXXX_XXXX______SSSS_EEEE_TTTT_RRRR_EEEE_GGGG_SSSS (line
  82.      9), the driver copies user data to the device registers (line 11).  If
  83.      the user address is invalid, an error code is returned.
  84.  
  85.       _1111  _ssss_tttt_rrrr_uuuu_cccc_tttt  _dddd_eeee_vvvv_iiii_cccc_eeee _{{{{     _////_**** _dddd_eeee_vvvv_iiii_cccc_eeee _rrrr_eeee_gggg_iiii_ssss_tttt_eeee_rrrr_ssss _llll_aaaa_yyyy_oooo_uuuu_tttt _****_////
  86.           _...._...._....
  87.       _2222   _iiii_nnnn_tttt _cccc_oooo_mmmm_mmmm_aaaa_nnnn_dddd_;;;;   _////_**** _dddd_eeee_vvvv_iiii_cccc_eeee _cccc_oooo_mmmm_mmmm_aaaa_nnnn_dddd _wwww_oooo_rrrr_dddd _****_////
  88.       _3333  _}}}}_;;;;
  89.       _4444  _eeee_xxxx_tttt_eeee_rrrr_nnnn _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_eeee_vvvv_iiii_cccc_eeee _xxxx_xxxx______dddd_eeee_vvvv_[[[[_]]]]_;;;; _////_**** _pppp_hhhh_yyyy_ssss_iiii_cccc_aaaa_llll _dddd_eeee_vvvv_iiii_cccc_eeee _rrrr_eeee_gggg_iiii_ssss_tttt_eeee_rrrr_ssss _****_////
  90.          _...._...._....
  91.       _5555  _xxxx_xxxx_iiii_oooo_cccc_tttt_llll_((((_dddd_eeee_vvvv______tttt _dddd_eeee_vvvv_,,,, _iiii_nnnn_tttt _cccc_mmmm_dddd_,,,, _vvvv_oooo_iiii_dddd _****_aaaa_rrrr_gggg_,,,, _iiii_nnnn_tttt _mmmm_oooo_dddd_eeee_,,,, _cccc_rrrr_eeee_dddd______tttt _****_cccc_rrrr_pppp_,,,, _iiii_nnnn_tttt _****_rrrr_vvvv_pppp_))))
  92.       _6666  _{{{{
  93.       _7777   _ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_eeee_vvvv_iiii_cccc_eeee _****_dddd_pppp_;;;;
  94.       _8888   _ssss_wwww_iiii_tttt_cccc_hhhh _((((_cccc_mmmm_dddd_)))) _{{{{
  95.       _9999   _cccc_aaaa_ssss_eeee _XXXX_XXXX______SSSS_EEEE_TTTT_RRRR_EEEE_GGGG_SSSS_::::    _////_**** _cccc_oooo_pppp_yyyy _uuuu_ssss_eeee_rrrr _pppp_rrrr_oooo_gggg_rrrr_aaaa_mmmm _dddd_aaaa_tttt_aaaa _tttt_oooo _dddd_eeee_vvvv_iiii_cccc_eeee _rrrr_eeee_gggg_iiii_ssss_tttt_eeee_rrrr_ssss _****_////
  96.      _1111_0000        _dddd_pppp _==== _&&&&_xxxx_xxxx______dddd_eeee_vvvv_[[[[_gggg_eeee_tttt_mmmm_iiii_nnnn_oooo_rrrr_((((_dddd_eeee_vvvv_))))_]]]]_;;;;
  97.      _1111_1111        _iiii_ffff _((((_cccc_oooo_pppp_yyyy_iiii_nnnn_((((_aaaa_rrrr_gggg_,,,, _((((_cccc_aaaa_dddd_dddd_rrrr______tttt_))))_dddd_pppp_,,,, _ssss_iiii_zzzz_eeee_oooo_ffff_((((_ssss_tttt_rrrr_uuuu_cccc_tttt _dddd_eeee_vvvv_iiii_cccc_eeee_))))_))))_))))
  98.      _1111_2222             _rrrr_eeee_tttt_uuuu_rrrr_nnnn _((((_EEEE_FFFF_AAAA_UUUU_LLLL_TTTT_))))_;;;;
  99.      _1111_3333        _bbbb_rrrr_eeee_aaaa_kkkk_;;;;
  100.  
  101. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  102.      _bbbb_cccc_oooo_pppp_yyyy(D3), _cccc_oooo_pppp_yyyy_oooo_uuuu_tttt(D3), _uuuu_iiii_oooo_mmmm_oooo_vvvv_eeee(D3), _uuuu_rrrr_eeee_aaaa_dddd_cccc(D3), _uuuu_wwww_rrrr_iiii_tttt_eeee_cccc(D3)
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.                                                                         PPPPaaaaggggeeee 2222
  128.  
  129.  
  130.  
  131.